/**
 *   _                                                          _   
 *  | | ____ _ _ __ _ __ ___   __ _  ___           _ __ ___ ___| |_ 
 *  | |/ / _` | '__| '_ ` _ \ / _` |/ __|  _____  | '__/ _ | __| __|
 *  |   < (_| | |  | | | | | | (_| | (__  |_____| | | |  __|__ \ |_ 
 *  |_|\_\__,_|_|  |_| |_| |_|\__,_|\___|         |_|  \___|___/\__|
 *         
 *  Copyright  2011 Kondra, Inc. 
 * 
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at:
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */

package com.kondra.karmac.rest
{
   /**
    * Interface for implementing service tasks.
    * 
    * @author Jared Kaplan
    */ 
   public interface IServiceTask
   {
      /**
       * Invokes the service request represented by this service task object.
       */ 
      function start() : void;
      
      /**
       * Cancels the service request if it is currently running.
       */ 
      function cancel() : void;
      
      /**
       * Set a flag in the service task that will attempt to retry the request
       * if it fails due to an http error.
       */ 
      function retry() : void;
      
      /**
       * Returns the number of retry attempts that have been made.
       */ 
      function getRetryCount() : int;
      
      /**
       * Returns <code>true</code> if the task has been completed.
       */ 
      function isComplete() : Boolean;
      
      /**
       * Get the unique id for this task. Every task that is executed has a
       * unique auto incremented id.
       */ 
      function getId() : int;
      
      /**
       * Returns the number of milliseconds the task took to complete. If the 
       * task is still running this method will return the elapsed time since
       * the task was invoked.
       */ 
      function getTime() : int;
      
      /**
       * Returns the number of bytes that have been loaded by the request.
       */ 
      function getSize() : int;
      
      /**
       * Returns the url that was used to invoke the request.
       */
      function getUrl() : String
         
      /**
       * Adds a notification handler to the request.
       * 
       * @param handler             The service notification handler object to add to the task
       * 
       * @see ServiceNotificationHandler
       */ 
      function addNotificationHandler( handler:ServiceNotificationHandler ) : void;
   }
}